home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 October / EnigmA AMIGA RUN 01 (1995)(G.R. Edizioni)(IT)[!][issue 1995-10][Aminet 7].iso / Aminet / mus / misc / maplay1_2.lha / maplay / INSTALL < prev    next >
Text File  |  1994-06-23  |  10KB  |  195 lines
  1. /*
  2.  *  @(#) MPEG Audio Player maplay 1.2, last edit of this file: 6/23/94 13:02:50
  3.  *  @(#) Copyright (C) 1993, 1994 Tobias Bading (bading@cs.tu-berlin.de)
  4.  *  @(#) Berlin University of Technology
  5.  *
  6.  *  This program is free software; you can redistribute it and/or modify
  7.  *  it under the terms of the GNU General Public License as published by
  8.  *  the Free Software Foundation; either version 2 of the License, or
  9.  *  (at your option) any later version.
  10.  *
  11.  *  This program is distributed in the hope that it will be useful,
  12.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  *  GNU General Public License for more details.
  15.  *
  16.  *  You should have received a copy of the GNU General Public License
  17.  *  along with this program; if not, write to the Free Software
  18.  *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  19.  */
  20.  
  21.  
  22. 0) Already tested platforms
  23.  
  24. The source code of this second release of maplay has been successfully tested
  25. with the following configurations:
  26.  
  27.  - SPARCstations with SunOS 4.1.1, SunOS 4.1.3, Solaris 2.2 (SunOS 5.2),
  28.    Solaris 2.3 and GNU C++ 2.5.1, gcc 2.5.4
  29.  - SGI with IRIX 4.0.5F, GNU C++ 2.5.1, gcc 2.5.4
  30.    maplay can't be compiled under IRIX 5.x, because of the missing audio
  31.    library, but binaries created under IRIX 4.0.5F work under IRIX 5.x, too.
  32.  - '486 under Linux, GNU C++ and gcc
  33.  - DECstation with ULTRIX 4.2, GNU C++ 2.5.1, gcc 2.5.8
  34.    maplay can be used as a decoder only on these machines, because the
  35.    DECstations I saw had not audio device.
  36.  
  37. -------------------------------------------------------------------------------
  38.  
  39. 1) Compiling the sources
  40.  
  41. If you have the GNU C++ compiler installed and have a SPARC 10, a SPARC LX
  42. (not tested yet, just read in the manpage of the dbri device), an Silicon
  43. Graphics Indigo or a 16 bit soundcard under Linux, simply say "make it so".
  44. If make didn't create a working binary, please read ahead.
  45.  
  46. If you have a SPARC with just an amd device, like a SPARC 2, SPARC IPX,
  47. SPARC classic etc., all I can give you is telephone quality output,
  48. because this device isn't capable of more. If your system release is
  49. SunOS 4.1.1 and you have GNU C++ installed, say "make it so". If your
  50. SunOS release is not 4.1.1 or you have another C++ compiler than g++,
  51. please take a look at the shell script configuration.sh. If your machine
  52. has an amd device, please add the -DULAW flag to the variable COMPILERFLAGS.
  53. configuration.sh specifies values for the following environment variables:
  54.  
  55.   COMPILER        Put the name of your C++ compiler in here, "g++" for
  56.             example. You may specify the full path for your
  57.             compiler if make doesn't find the compiler.
  58.   COMPILERFLAGS        This variable contains compiler flags for your
  59.             compiler. The -D flags together with #ifdefs in the
  60.             sources create the (hopefully) correct program for your
  61.             machine. You should not change these defines.
  62.             If you have a SPARC 2/IPX/... with an amd audio
  63.             device, you should add the -DULAW flag to this
  64.             variable.
  65.             Other flags are for optimizations, like "-O2" for the
  66.             GNU g++, warning output control    etc.
  67.             What the define "-DDAMN_INTEL_BYTE_ORDER" does
  68.             should be obvious. It has to be defined on machines
  69.             which use the same byte    order as Intel processors.
  70.             (Intel byte order is lowest-byte-first)
  71.   INCLUDEDIRS        This variable isn't needed anymore, unless your
  72.             compiler don't know where to find his own include
  73.             files. In this case, put -I options for include file
  74.             paths for your compiler    in here.
  75.   LIBRARIES        This variable should contain -l options needed by
  76.             your compiler for linking the program. The math
  77.             library is automatically included in the makefile.
  78.   AUDIO_INCLUDES    Audio include files, like audio.h or audioio.h, are
  79.             often placed in different directories on different
  80.             machines. Put the correct include directive for your
  81.             machine in here, for example "#include <sys/audio.h>".
  82.  
  83. The script configuration.sh contains a big switch statement, which tests the
  84. output of the command "uname -sr". This command should return the name and
  85. release of your operating system. You should enter this command in a shell
  86. first, to see if the output matches one of the already existing case entries.
  87. If so, you can modify the environment settings of this entry according to your
  88. needs. If your operating system and/or release hasn't been tested by now,
  89. you may enter your own entry according to the "uname -sr" output and put in
  90. your environment settings then (see 1.1: Compiling on new platforms).
  91. If your operating system does not know a uname command, you may write a shell
  92. script named "uname" containing
  93. "echo Your_System 1.23"
  94. and add an entry in the configuration.sh file. Or you can throw away the switch
  95. statement and leave only your environment settings in the script file.
  96.  
  97. After you have modified configuration.sh, you can run "make" to start
  98. compiling. I hope you will be rewarded with an executable after doing so.
  99. If the compilation process didn't make it till the end, you may try to
  100. fix the problem. If you need to adjust the environment settings mentioned
  101. above, you should execute "make clean" thereafter and then "make" again.
  102. If you don't get the problem fixed, you can send me an email (to
  103. bading@cs.tu-berlin.de) wherein you describe your problem. You can also send
  104. me an email, if you successfully compiled the program, but needed to do
  105. some changes to the sources. These changes may also be useful for other users,
  106. so I can include your changes in the next release.
  107.  
  108. I am interested in any experiences in compiling the program on other machines,
  109. because I can't test the program on any existing type of machine myself.
  110. Bug reports etc. should be send to bading@cs.tu-berlin.de, too.
  111.  
  112. -------------------------------------------------------------------------------
  113.  
  114. 1.1) Compiling on new platforms
  115.  
  116. Due to the fact that you are using a computer on which I have not tested the
  117. program yet, everthing can happen while compiling the program (who knows?).
  118. Besides, even if your computer has an audio device with CD-quality, the program
  119. cannot use it, because each device has a different programming interface, like
  120. a library or ioctls etc. and maplay 1.2 only contains drivers for Indigos,
  121. SPARCs and Linux machines. But if you have enough informations about your
  122. audio device and some knowledge in C/C++, who can write your own output class.
  123. If you are interested, take a look at chapter 1.2. If you want to use the
  124. program as a decoder only, you do not have to worry about this.
  125.  
  126. Ok, now here is what you should do to get the program running on your machine:
  127. a) Create a new entry in configuration.sh according to your "uname -sr" output.
  128. b) Set the environment variables COMPILER and LIBRARIES to values usefull on
  129.    your machine.
  130. c) Leave AUDIO_INCLUDES empty. If you want to write your own output class, you
  131.    may need this variable.
  132. d) Include the following options into the variable COMPILERFLAGS:
  133.    - the best possible optimization option(s) for your compiler
  134.      (-O2 for example)
  135.    - -DDAMN_INTEL_BYTE_ORDER, if your machine uses Intel byte order.
  136.      (Intel byte order is least significant byte first)
  137.      If you do not know which byte order is used by your machine, try it
  138.      without this define first. If the program creates warnings and you get
  139.      nothing but noise as output, you should add this define, execute
  140.      "make clean ; make" and try it again.
  141.    Do not insert the defines "-DIRIX", "-DIndigo", "-DSolaris", "-DSunOS",
  142.    "-DSunOS4_1_1", "-DSunOS4_1_3", "-DSPARC", "-DLINUX", "-DULTRIX" or "-DDEC"
  143.    into COMPILERFLAGS. But you can create new define names for your machine.
  144.  
  145. I hope you get a working executable after modifying configuration.sh and
  146. running make. If that is not the case, you have two options:
  147. 1. Try to fix the problem yourself with new #ifdefs in the sources.
  148. 2. Send me an email describing your problems.
  149.  
  150. -------------------------------------------------------------------------------
  151.  
  152. 1.2) Writing a new output class
  153.  
  154. Ok, you want to write a new output class?
  155. Then take a look at the file obuffer.h first. The Class Obuffer is an
  156. abstract base class for all audio output classes. Currently implemented
  157. derived classes are:
  158. - class FileObuffer for raw PCM output to a filedescriptor
  159. - class IndigoObuffer for audio playback on Silicon Graphics Indigo machines
  160. - class SparcObuffer for audio playback on Sun SPARC 10 machines with the
  161.   dbri device
  162. - class LinuxObuffer for audio playback on 16 bit soundcards under Linux
  163.   using the /dev/dsp device
  164.  
  165. To access your audio device, the program needs a new class derived from
  166. Obuffer written for this device. The new class has to implement the
  167. following methods:
  168. - a constructor
  169.   The constructor has to configure the audio device. It should set the
  170.   number of channels (mono or stereo) and the sample frequency (32, 44.1 or
  171.   48 kHz) according to the mode of the audio stream. These informations should
  172.   be included in the parameters of the constructor. The sample format is
  173.   always 16 bit signed PCM.
  174. - void append (uint32 channel, int16 value)
  175.   This function takes a channel number (0 for left or 1 for right) and a
  176.   PCM sample. The sample should be stored in an array for later output.
  177. - void write_buffer (int fd)
  178.   This function should transfer samples from previous calls to append() to the
  179.   audio device. Samples are not written to the audio device in append(),
  180.   because a syscall takes too much time. The parameter is a dummy here.
  181.  
  182. You can take the implementations in obuffer.cc as a guideline.
  183. To use your class, the main function in maplay.cc has to be modified. Simply
  184. remove the //s in lines 322-336 and fill in your class name, parameters etc.
  185.  
  186. If you have implemented a new output class, you will be rewarded with the
  187. great quality of MPEG audio. And if you think that other users might like
  188. your class too, sent me a copy of your sources and I will include it in the
  189. next release.
  190.  
  191.  
  192. That's all for now and this release,
  193. bye,
  194.      Tobias Bading   (bading@cs.tu-berlin.de)
  195.